Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / SIMIIE.ZIP;1 / SIMIIE.DOC < prev next >

Wrap

Text File | 1994-04-07 | 48.1 KB | 1,016 lines

Page 1 SimSystem IIe - Version 1.0 Shareware Copyright (c) 1994 by American Research Inc. Developed by Jim Sproul All Rights Reserved I N T R O D U C T I O N SimSystem IIe is amazing! It will make your PC compatible computer system look, sound, and act just like an Apple IIe computer! With SimSystem IIe you will be able to run your favorite Apple II software. SimSystem IIe supports all standard Apple graphics modes, so your favorite Apple games will work perfectly. Even the sound is reproduced exactly! SimSystem IIe supports all of the standard keys on an Apple IIe keyboard, including the Open Apple and Solid Apple keys. And, SimSystem IIe will let you use your PC joystick with Apple programs that require a joystick. SimSystem IIe simulates an Apple IIe compatible computer with FOUR DISK DRIVES! Two are simulated 5 1/4 inch diskette drives, and two are ProDOS compatible hard disk drives. You can swap disks anytime by pressing a function key and selecting another 'disk'. You can even swap disks on the two simulated hard drives! And, SimSystem IIe emulates the Apple Disk II floppy drive so well that you can even use some copy protected programs with SimSystem IIe! SimSystem IIe does MORE than a real Apple IIe! Programmers will love the enhanced 65C02 monitor! And, the built-in debugger is as powerful as an expensive in-circuit emulator! SimSystem IIe can simulate an Apple IIe with a color or monochrome monitor. The VGA display mode is breathtaking - you'll swear you're looking at an Apple IIe display! And, SimSystem IIe works with CGA and EGA display adaptors, too! Don't forget - SimSystem IIe is SHAREWARE! Registered users get the latest updated version of SimSystem IIe, a nicely printed and bound manual (with pictures...), and the SimDisk utility (for creating 'disks' for use with SimSystem IIe). This manual provides a brief overview of SimSystem IIe. Registered users receive complete in-depth documentation. Page 2 T A B L E O F C O N T E N T S Introduction..................................Page 1 Legal Statement...............................Page 3 Chapter 1 - Features..........................Page 5 Chapter 2 - System Requirements And Compatibility...............................Page 6 Chapter 3 - Performance.......................Page 7 Chapter 4 - Installation Guide................Page 8 Chapter 5 - Getting Starting: SimSystem IIe Configuration...............................Page 9 Chapter 6 - Volume Files: The SimSystem IIe Disk Drives.................................Page 13 Chapter 7 - Booting The Emulator: The Volume Selector.............................Page 14 Chapter 8 - The Emulator Keyboard.............Page 16 Chapter 9 - SimSystem IIe Function Keys.......Page 17 Chapter 10 - The SimSystem IIe Debugger.......Page 19 Chapter 11 - Volume File Formats..............Page 21 Appendix - Registration.......................Page 23 Page 3 Legal Statement _______________ SimSystem IIe was developed by Jim Sproul for American Research Inc. SimSystem IIe is copyright (c) 1994 by American Research Inc. SimSystem IIe and SimSystem are trademarks of American Research Inc. All rights reserved. COPYRIGHTS AND TRADEMARKS USED IN THIS DOCUMENT Apple, Apple IIe, Apple DOS, and Apple ProDOS are trademarks of Apple Computer Corporation. AppleWorks is a trademark of Claris Corporation. MS-DOS is a trademark of Microsoft Corporation. IBM is a trademark of International Business Machines Inc. SIMSYSTEM IIE IS SHAREWARE. License is hereby granted to the end user to use SimSystem IIe for a period of ten days for the purpose of evaluating the usefulness of the software. After that time the software must be purchased by sending the registration fee, currently $50 US, to American Research Inc. If the registration fee is not paid after ten days the end user must stop using the software, and must destroy any copies of the program in his/her possession. Instructions for registering SimSystem IIe are provided at the end of this document. Bulletin Board System (BBS) operators may receive a free registration for SimSystem IIe by making SimSystem IIe available on their BBS system, and sending in the SimSystem IIe registration form along with instructions for accessing the BBS. After verifying that SimSystem IIe is available, and that the conditions of distribution are being met, we will send the registered version of SimSystem IIe, a printed and bound manual, and the SimDisk utility. The ten day evaluation period is waived for BBS operators who make SimSystem IIe available on their BBS system, and who comply with the terms of distribution given below. DISTRIBUTION SimSystem IIe may be distributed, either on magnetic media or via modem, for the purpose of exposing the product to other potential users, providing that all original files are included, intact and unmodified, and that no additional files are provided in association with the product. SimSystem IIe may NOT be distributed on a bulletin board system (BBS) that illegally distributes copyrighted commercial software. COMMERCIAL SHAREWARE DISTRIBUTION SimSystem IIe may be distributed by commercial shareware distribution firms provided that the terms of distribution outlined above are complied with, and that the shareware nature of the product is CLEARLY stated on the product packaging and on the media (diskette, CD, etc.). SIMSYSTEM IIE IS AN ORIGINAL PRODUCT Page 4 SimSystem IIe was written by Jim Sproul for American Research Inc. The program was written in 80286 assembly language, except for the interpreted pseudo-ROM program, which was written in 65C02 assembly language. SimSystem IIe does NOT contain any program code in any form (interpreted or executable) which is the copyrighted property of Apple Computer. (This becomes apparent if the user examines the 65C02 monitor program.) USE OF COMMERCIAL SOFTWARE WITH SIMSYSTEM IIE The end user MUST have a license from the software publisher to use any commercial software with SimSystem IIe. This license is usually granted, with some limitations, when the user purchases the software. Some software licenses may stipulate that the software may only be used on a computer system which is manufactured by, or under license from, Apple Computer. Software products bearing such a license stipulation may NOT be used legally with SimSystem IIe. WARNING: The use of commercial software products with SimSystem IIe which are not obtained through legal means (i.e., purchased) is ILLEGAL! DISCLAIMER SimSystem IIe is provided solely for the amusement of the user. American Research Inc. makes no guarantee regarding the usefulness of the product, and does not guarantee that the product will operate uninterrupted, or will be free of errors. American Research Inc. will not be responsible for any damages resulting from the failure of the product to perform as expected. The user is urged to read this document in its entirety (especially the Compatibility Guide) before using SimSystem IIe. Page 5 Chapter 1 - Features ____________________ SimSystem IIe is configured to emulate an Apple IIe with the following features: * 128K RAM (64K main / 64K auxiliary) * 65C02 microprocessor * Parallel printer adaptor in 'slot 1' * 80-column display adaptor in 'slot 3' * Dual floppy drive adaptor in 'slot 6' * Dual hard drive adaptor (removeable media) in 'slot 7' In addition, SimSystem IIe has the following features: * Supports CGA, EGA, and VGA display adaptors. * Emulates all standard Apple display modes, including 40 column text, 80 column text, low resolution graphics, high resolution graphics, and double high resolution graphics. * Emulates full Apple keyboard, including Open Apple and Solid Apple keys. * Emulates Apple joystick using standard PC game port. * Emulates Apple internal speaker sound. * Built-in enhanced 65C02 monitor. * Built-in 65C02 debugger supports breakpoints, single step, register display, and more. * Use files on your hard disk as 'disks' for four simulated disk drives. Swap disks anytime by pressing a function key (even on the simulated hard drives). * Special set-up screen lets you choose your PC video mode, select printer and game port, turn on/off sound, enable/disable debugger, etc. Save your configuration and SimSystem IIe will always start up the way you want it to. Page 6 Chapter 2 - System Requirements And Compatibility _________________________________________________ SimSystem IIe requires a 100% IBM compatible computer system with an 80286 (or downward compatible) microprocessor. A graphics display adaptor (CGA, EGA, or VGA) is required. A parallel printer adaptor and game port are also optional. Although not required, a hard disk is highly recommended for maximum performance. SimSystem IIe will NOT work on systems with an 8086, 8088, or V20 microprocessor. SimSystem IIe is NOT compatible with Microsoft Windows, and may not be run as a DOS task under Windows. SimSystem IIe changes the keyboard interrupt vector, and deals directly with system hardware for maximum performance. SimSystem IIe is known to be incompatible with many IBM portable computers, and Viglen computer systems (manufactured in the U.K.). If you find SimSystem IIe does not function on your computer system please write to American Research Inc., at the address provided, and describe your computer system and the symptoms of the problem. If we find the problem is due to a bug in SimSystem IIe we will send you a registered copy of SimSystem IIe at no charge! Page 7 Chapter 3 - Performance _______________________ The performance of SimSystem IIe, as compared to a real Apple IIe, will vary considerably. This depends on the type and speed of your microprocessor, the number of wait states imposed by your system memory, the speed of your display adaptor, etc. SimSystem IIe running on an 80286 system operating at 12 MHz will be painfully slow, and probably not useful for anything except the most mundane tasks. If you have a system like this then you may not be bothered by the lackluster performance, as you are probably already used to a lot of waiting. You might consider donating your system to your local Salvation Army Thrift Store or elementary school. SimSystem IIe running on an 80386 system operating at 20 MHz will show adequate performance for most text based tasks, such as AppleWorks. However, video games will probably not offer enough of a challenge for anyone over the age of six. SimSystem IIe running on an 80486SX system operating at 25 MHz will perform well beyond the speed of an Apple IIe for computational uses, but will perform at about the same speed for graphics operations. You can improve the performance of SimSystem IIe by operating the program in CGA mode (even if you have an EGA or VGA display adaptor), and by using the program with the debugger option turned off. Page 8 Chapter 4 - Installation Guide ______________________________ Since you are reading this document you have already discovered that the first step in installing SimSystem IIe is to extract the individual files from the archive (SIMIIE.ZIP). SimSystem IIe comes with the following files: SIMIIE.EXE - the SimSystem IIe program MON.ROM - the SimSystem IIe 65C02 monitor program SLOT.ROM - the SimSystem IIe 65C02 expansion slot programs DIAG.ROM - the SimSystem IIe 65C02 resident programs EXP.ROM - the SimSystem IIe expansion programs DEMO.IIE - a simple game developed with SimSystem IIe FLOBYN.IIE - a public domain game for the Apple IIe SIMIIE.DOC - this file We strongly recommend that you copy all of these files into a single subdirectory on your PC hard drive. We usually name this subdirectory SIMIIE. All of the files with the 'ROM' extension are 65C02 programs that SimSystem IIe uses for its simulated ROM memory. SimSystem IIe looks for these files in the current directory on startup. Page 9 Chapter 5 - Getting Started: SimSystem IIe Configuration ________________________________________________________ You can run SimSystem IIe by typing the following command at the MS-DOS prompt: SIMIIE<Enter> Of course, the phrase <Enter> means to press the Enter key. If SimSystem IIe does not find a valid SIMIIE.CFG file in the startup directory then you will be presented with the SimSystem IIe configuration screen. This screen allows you to select options for SimSystem IIe, which you can save for future use. Even after saving your preferred configuration in the SIMIIE.CFG file you can still change the configuration later by entering: SIMIIE /S<Enter> This command will cause SimSystem IIe to load the SIMIIE.CFG configuration and display the configuration screen so that you may make changes. Should you ever wish to restore the factory default configuration you can simply erase the SIMIIE.CFG file from your startup directory, and SimSystem IIe will start just like the first time you used it. Each of the configuration options is described below. 1...Video Mode Pressing the '1' key will cycle through each of the available video mode options. These options refer to the PC video mode which SimSystem IIe will use when simulating the Apple IIe display. All Apple IIe display modes are supported by SimSystem IIe regardless of which PC display mode you choose. CGA display mode uses a graphics screen which is 640 dots wide, and 200 dots high, and is black-and-white. When this option is selected SimSystem IIe will simulate an Apple IIe with a monochrome monitor. This is the only option that will work for PC computer systems with a CGA display adaptor. However, since screen graphics operate much faster in this mode, owners of EGA or VGA equipped computers might choose to use this mode for some graphics intensive programs. EGA display mode uses a graphics screen which is 640 dots wide, and 200 dots high, and uses 16 colors. In this mode SimSystem IIe will simulate an Apple IIe with a color display. This mode can be used with EGA and VGA equipped systems. This mode is also compatible with computers having an EGA display adaptor and a non-enhanced (CGA) monitor. VGA equipped machines pose a special problem for SimSystem IIe. The quality of the display produced by the VGA display adaptor is much higher than that of a real Apple IIe, making it difficult to produce a realistic looking display. The Apple IIe display only uses half of the available scan lines, leaving a thin black stripe between rows of dots. In low resolution display modes the VGA display adaptor will actually display each row of dots twice in order to fill in the black space. While this process, called Page 10 double scanning, might produce a better looking PC display screen, it makes a simulated Apple IIe display look bright and chunky. SimSystem IIe compensates for this by operating the VGA display adaptor in the 640 by 480 dot display mode, and intentionally skipping alternating rows of dots. This adds the original black space between rows of dots, producing a strikingly realistic display. 2...Printer Port SimSystem IIe simulates an Apple IIe with a parallel printer adaptor card installed in 'slot 1'. This option allows you to choose which printer port on your PC to use when an Apple II program is sending data to your printer. Pressing the '2' key will cycle through the available options. If you don't have a printer attached to your PC, or if you choose not to use a printer with SimSystem IIe, then you can select the 'NONE' option. 3...Modem Port This option is provided in the event a future version of SimSystem IIe is written that supports a modem card in 'slot 2'. The current version of SimSystem IIe does not support this. 4...Game Press the '4' key to toggle this option between 'ON' and 'OFF'. When this option is set 'ON' SimSystem IIe will support the use of a PC joystick with Apple II programs that require a joystick or paddles. If your PC system is not equipped with a game port or joystick, or you don't wish to use a joystick with any Apple programs, then set this option to 'OFF'. 5...Mouse This option is provided in the event a future version of SimSystem IIe is written that supports a mouse card in 'slot 4'. The current version of SimSystem IIe does not support this. 6...Sound Press the '6' key to toggle this option between 'ON' and 'OFF'. When this option is set 'ON' SimSystem IIe will simulate Apple IIe sound through the internal speaker on your PC. If your PC is an older (and slower) machine than you might find the simulated audio annoying, and you may wish to set this option to 'OFF'. A through G...Emulator System These options are provided to remind you which simulated expansion cards are installed in each SimSystem IIe 'slot'. A future version of SimSystem IIe might allow you to select different simulated cards for each slot. Page 11 H...Debugger Press the 'H' key to alternate between ON and OFF. The SimSystem IIe debugger will allow programmers direct access to the simulated 65C02 microprocessor. Using the debugger you can stop the processor, display the contents of the 65C02 registers, step through the program one instruction at a time, and set hardware breakpoints, all without any adverse affect on the program being run. SimSystem IIe will operate more slowly while the debugger is enabled, so you should switch it off unless you need to use it. Use of the SimSystem IIe debugger is described in detail in chapter 10. I...Page Flip The Apple IIe provides two video display buffers for most display modes, and SimSystem IIe supports this. Some programs will display the image from one of the two display buffers while creating another image in the alternate buffer. When the image is completed the program will switch the display to the alternate display buffer using a technique called 'page flipping'. SimSystem IIe tries to be intelligent about page flipping, and only redraws the portion of the display screen which has actually changed. While this works fine for most graphics programs, some programs will page flip between two completely different display screens, causing SimSystem IIe to do a lot of screen drawing. If you find a graphics program is operating more slowly with SimSystem IIe, and you suspect that page flipping is the problem, you might try running the program with the page flipping option turned OFF. This will force SimSystem IIe to display only one display buffer. You can select which of the two buffers is displayed while the program is running by pressing the F6 key. (Use of the F6 key is described in chapter 9.) J...Flash Text Both the Apple IIe and the PC support a form of flashing text when the display is operating in text mode. On the Apple IIe the text will alternate between normal (white on black) and inverse (black on white) at regular intervals. On the PC the text will alternate between on and off. SimSystem IIe supports the Apple IIe style flashing text by periodically redrawing the flashing characters in reverse. While this produces a very realistic simulated Apple display, it can cause a noticeable decrease in performance on slower machines. Turn this option OFF if you suspect that flashing text is a problem. R...Run SimSystem IIe Select this option to start the SimSystem IIe emulator. S...Save Configuration Select this option to save the current configuration in the SIMIIE.CFG file. If the file already exists it will be replaced. Page 12 Once this file has been created SimSystem IIe will not automatically enter the configuration mode on startup unless the /S switch is provided on the command line. Esc...Return to DOS If, after making changes to the configuration screen, you do not wish to start the SimSystem IIe emulator, you may return to the MS-DOS prompt by pressing the Esc key. Page 13 Chapter 6 - Volume Files: The SimSystem IIe Disk Drives _______________________________________________________ SimSystem IIe emulates an Apple IIe with four disk drives, two floppy drives and two hard drives. These simulated disk drives exist only in software, which is to say that the disk drives don't physically exist. An Apple II program will find all of the appropriate hardware registers for these disk drives only because SimSystem IIe simulates these registers. In fact, SimSystem IIe simulates these disk drives so well that many copy protected programs will work. These simulated disk drives need simulated disks in order to work. These disks are provided in the form of files on your PC hard drive. In most cases, these files contain a complete copy of the contents of a real Apple disk. We call these 'volume files'. Volume files for use with the simulated floppy drives will have the MS-DOS extension *.IIE, while files for use with the simulated hard drives will have the MS-DOS extension *.HDV. SimSystem IIe provides a special file selector that allows you to swap disks in any of the simulated disk drives (including the simulated hard drives) by simply selecting another volume file. A floppy volume file (*.IIE) will always contain 143360 bytes of data, while a hard drive volume file (*.HDV) may vary between 800K and 16M. The Apple ProDOS 3 1/2 inch diskettes can be simulated by using 800K hard drive volumes. The simulated hard drive conforms to Apple ProDOS standards, and can only be used with ProDOS. Floppy volume files (*.IIE) can contain data in two different formats; binary and GCR. Binary format files are always 143390 bytes in length, while GCR format files will vary in length (usually greater than 200K). Binary format files are used for most applications where program code or data is stored in standard Apple format, and no copy protection is used. GCR format files contain a copy of the disk data in its purest GCR encoded format, the same way it is stored on a real Apple II diskette. SimSystem IIe does not interpret or translate GCR data in any way, whichs makes this format suitable for many copy protection methods used on Apple II products. You will need the SimDisk program in order to create volume files for SimSystem IIe. This program allows you to download Apple compatible programs via modem, or directly from an Apple II computer system. You can also use a Deluxe Option Board, from Central Point Software, to directly read Apple diskettes in your PC floppy drive. SimDisk is provided to registered users of SimSystem IIe. Page 14 Chapter 7 - Booting The Emulator: The Volume Selector _____________________________________________________ You can start the SimSystem IIe emulator by selecting the 'R' option from the configuration screen. If you have saved your configuration in the SIMIIE.CFG file, then the emulator will start automatically when you run the SIMIIE program. Just like a real Apple IIe, the first thing SimSystem IIe will try to do is load an operating system from one of the simulated disk drives. This process is called 'bootstrap', or booting. SimSystem IIe provides the Volume Selector to allow you to choose a volume file for any of the simulated disk drives. The Volume Selector is displayed at startup so that you can select a volume file to boot. You can also call up the Volume Selector at any time while using SimSystem IIe by pressing the F7 function key. If your keyboard fails to work at this point it is probably because your PC keyboard system is not 100% IBM compatible, as required for SimSystem IIe. If this is the case then SimSystem IIe will NOT work with your computer. Please write to American Research at the address provided at the end of this manual, and let us know what kind of computer system you are using. The Volume Selector is displayed using the simulated Apple 80-column display characters. The Volume Selector box is outlined in inverse box characters, and contains the title 'VOLUME' at the top. Inside the box are listed up to eight files or subdirectories on your PC hard drive. If the file listed is a subdirectory then the letter 'D' will appear in the border to the left of the filename. The selected disk drive is listed in the bottom border of the box after the word 'TAB' in the format 'SnDn'. The number following the 'S' indicates the 'slot', where slot 6 is the two simulated floppy drives, and slot 7 is the two simulated hard disk drives. The number following the 'D' indicates which of the two simulated disk drives in each slot is selected, either 1 or 2. By pressing the TAB key you can alternate between S6D1, S6D2, S7D1, and S7D2. Note that when either of the two simulated floppy drives (slot 6) are selected then only files with the extension *.IIE will be displayed. Similarly, when either of the two simulated hard drives (slot 7) are selected then only files with the extension *.HDV will be displayed. All subdirectories will be displayed regardless of which simulated disk drive is selected. The selected file or subdirectory is displayed by highlighting its name in inverse characters (black on white). You can change the selected file or subdirectory by using the UP and DOWN arrow keys (also called cursor keys) on your PC keyboard. The list will scroll when the highlight bar reaches the bottom or top of the window, if more selections exist. You can choose a file or subdirectory by moving the highlight bar over the name and pressing the Enter key. If the selection is a subdirectory then the contents of that directory will be displayed in the window. You can move to the previous Page 15 subdirectory by selecting the '..' option from the list. If the selection is a volume file then that file will be 'installed' in the selected simulated disk drive, and the Volume Selector will disappear. The current MS-DOS path is displayed at the bottom of the screen. You can exit from the Volume Selector without choosing a file by pressing the Esc key. None of the selected volume files will be changed. Leaving the Volume Selector displayed at boot time by pressing the Esc key is equivalent to starting an Apple IIe without any disks in the disk drives. Like an Apple IIe, SimSystem IIe will run continuously trying to read a non-existent disk. However, just like an Apple IIe, you can press RESET (function key F5) to proceed directly to the built-in BASIC interpreter. Of course, no operating system is loaded so you won't be able to load or save any programs. However, you can still play with BASIC, or the built-in monitor program. Once you have selected a volume file SimSystem IIe will begin loading the operating system from the volume. After that, things works pretty much like a real Apple IIe! Page 16 Chapter 8 - The Emulator Keyboard _________________________________ Most of the keys on your PC keyboard work with the emulator. All of the alphanumeric keys are the same, including Esc, Shift, Ctrl, Tab, Caps Lock, Backspace, and the arrow (cursor) keys. Functions keys F1 through F10 are used for special SimSystem IIe commands, and are not used by any Apple II programs. The numeric keypad keys are equivalent to the numeric keys on the main keyboard. The Alt key to the left of the space bar is used for the Open Apple key. The Alt key to the right of the space bar is used for the Solid Apple Key. Note that the screen characters that represent these keys are replaced with Open Diamond and Solid Diamond (to avoid copyright problems with Apple Computer). None of the following keys perform any function with SimSystem IIe. Print Screen Scroll Lock Pause Insert Home Page Up Delete End Page Down Num Lock Some Apple operating systems, like Apple DOS, do not support all of the keys on an enhanced Apple IIe. For example, Apple DOS does not recognize lower case characters. However, like an Apple IIe, SimSystem IIe starts up in Caps Lock mode. In addition, Apple DOS and AppleSoft BASIC do not recognize the Backspace key, and use instead the left arrow key. In other words, use the keyboard just as you would on a real Apple IIe. Page 17 Chapter 9 - SimSystem IIe Function Keys _______________________________________ Some of the things you would do with a real Apple IIe are not directly possible with an emulator program. SimSystem IIe uses function keys F1 through F10 to perform these special tasks. The bar at the bottom of the screen is used to remind you of the purpose of these function keys. Please note that this reminder bar is temporarily replaced by the MS-DOS path when using the Volume Selector, and by the debugger display (when enabled). Each of the function keys is described below. F1 SHOW (Debugger) This key is used only when the SimSystem IIe debugger is enabled. This key allows you to alternate between the debugger display and the reminder bar. The debugger display is described in the chapter 10 of this manual. F2 SNGL (Debugger) This key is used only when the SimSystem IIe debugger is enabled. This key allows you to alternate between RUN and STEP mode. In RUN mode the simulated 65C02 processor will run continuously. In STEP mode the simulated 65C02 processor can be stepped one instruction at a time using function key F4. F3 BRK (Debugger) This key is used only when the SimSystem IIe debugger is enabled. This key allows you to set a breakpoint address. When the 65C02 processor reaches the breakpoint address it will automatically switch into the STEP mode (see function key F2 and F4 descriptions). F4 STEP (Debugger) This key is used only when the SimSystem IIe debugger is enabled. This key allows you to step the 65C02 processor one instruction at a time. This key is only effective when the 65C02 processor is in STEP mode (see function key F2 description). F5 RST This key is equivalent to the RESET key on a real Apple IIe. Pressing this key will cause the simulated 65C02 processor to be reset. Some Apple II programs will alter the 65C02 reset address, which prevents the program from being stopped. These programs will behave similarly with SimSystem IIe. See function key F9 description below. F6 FLIP This key is used when the Page Flip option (on the configuration screen) is turned OFF. Use this key with graphics mode programs to select which of the two display buffers will be shown on the Page 18 screen. Pressing this key will cause SimSystem IIe to switch between the two display buffers. This feature is useful to programmers who want to watch screen data being created in a display buffer that would normally be hidden from view. F7 DISK Use this key to access the Volume Selector. Use of the Volume Selector is described in chapter 7 of this manual. The Volume Selector is sometimes useful as a PAUSE function in some games, since the emulator stops while the Volume Selector is displayed. F8 JOY This key is only useful if the Game Port option is enabled (on the configuration screen). As you probably already know, not all PC joysticks are the same. In addition, not all PC game port adaptors are the same. Most PC games that use a joystick provide an option for 'calibrating' the stick to work properly with the game. SimSystem IIe provides function key F8 for this purpose. Position your joystick in the center position and press F8. A reminder box will pop up to inform you when the calibration is complete. THIS PROCESS MUST BE PERFORMED EVERY TIME YOU RUN SIMSYSTEM IIE, AND BEFORE USING THE JOYSTICK! If your joystick features calibration adjustments you should set them in the center position before pressing F8. The SimSystem IIe joystick emulation should work with virtually all Apple II games that use a joystick. F9 PWR Pressing this key is essentially the same as switching off an Apple IIe for a moment, then switching it back on. Use the Volume Selector to select a new disk to boot before pressing F9. F10 BYE Use this key to return to the MS-DOS prompt. No warnings are given, so press this key only if you want to leave SimSystem IIe. Page 19 Chapter 10 - The SimSystem IIe Debugger _______________________________________ The SimSystem IIe debugger is an advanced feature intended for programmers, and other technically inclined users. Most users will choose to operate SimSystem IIe with the debugger option (on the configuration screen) turned OFF, since it significantly reduces the speed at which SimSystem IIe operates. A traditional debugger is a program that resides in memory with the program being tested. The program under test must be reasonably well behaved in that it may not trash memory required by the debugger, or interact with system hardware in a manner the debugger doesn't expect, or both programs will crash. A debugger is also a useful tool for examining how another program works. Many copy protected programs, or programs which use proprietary software techniques or algorithms, are specifically designed so that a traditional debugger will not work with them. The SimSystem IIe debugger is different. It works more like a piece of hardware attached to the microprocessor, or an in-circuit emulator device. The SimSystem IIe debugger is not a program that coexists in 65C02 memory, but is an enhancement to the 65C02 microprocessor emulator program. In fact, the SimSystem IIe debugger was used extensively in testing SimSystem IIe. Using the SimSystem IIe debugger, you can view each instruction the 65C02 executes BEFORE it actually executes them. You can stop the processor at any time, view its register contents, single step through the instructions, and set hardware breakpoints at any address. Before you can use the SimSystem IIe debugger it must be enabled on the configuration screen. When you execute SimSystem IIe with the debugger enabled you will be presented with a box asking you to enter a breakpoint address in hexadecimal. When the 6502 program executes an instruction at the specified breakpoint address SimSystem IIe will automatically switch into STEP mode (stopping the processor), and the debugger display will automatically be turned on. SimSystem IIe will ONLY stop at breakpoint addresses where an instruction begins (i.e., where the 65C02 processor performs an opcode fetch). The debugger will NOT stop the 65C02 processor if the breakpoint address falls in the middle of an instruction. The breakpoint address you specify will remain in effect until you change it. If you don't want SimSystem IIe to stop at any address you may enter FFFF, since this address is part of the IRQ interrupt vector, and the 65C02 processor should NEVER execute an opcode fetch at this address. After entering the breakpoint address SimSystem IIe will behave as it otherwise would, although somewhat more slowly. Function keys F1 through F4 perform special debugger tasks, as described in chapter 9. Function key F1 will toggle the debugger display on and off. SimSystem IIe slows down even more with the debugger display on, since each instruction is displayed as it is executed. Page 20 Function key F2 will toggle between STEP and RUN mode. You can restart the 65C02 processor after a debugger breakpoint by pressing the F2 key. Function key F3 will display the Set Breakpoint box (just as it was displayed at the start of the program) so that you may enter a different breakpoint. You can step past a subroutine call by setting the breakpoint to the address of the first instruction after the JSR and pressing F2 to restart the 65C02. SimSystem IIe will return to STEP mode after the subroutine returns. Function key F4 is used to step the 65C02 processor a single instruction. The debugger display looks like this: PC=1234 SP=0180 A=00 X=FF Y=10 PS=NVBDIZC LDA ($30),Y $8010 The field 'PC=1234' tells us that the current instruction (program counter) is at address $1234. The field 'SP=0180' indicates the current address of the stack pointer. The fields 'A=00', 'X=FF', and 'Y=10' show the current contents of the three processor data registers. The field 'PS=NVBDIZC' show the processor status bits Negative, oVerflow, Break, Decimal, Interrupt disable, Zero, and Carry. The letter representing each bit is only displayed when the corresponding bit is ON, otherwise they are displayed as a period. The instruction at the current address is displayed (in this case, LDA ($30),Y). Since indirect addressing is used, the effective address is also displayed ($8010). Since the Y register contains $10, we can deduce that the indirect address at zero page location $30 and $31 is $8000. All of the other SimSystem IIe function keys will work normally even when the 65C02 processor is halted by the debugger. Page 21 Chapter 11 - Volume File Formats ________________________________ It is our hope that everyone who tries SimSystem IIe will find it useful, and will choose to pay the reasonable $50 registration fee. As an incentive, we offer the SimDisk program to registered users. With SimDisk you can create volume files for SimSystem IIe, copy files from MS-DOS to SimSystem IIe volumes (or vice versa), and generate volumes from real Apple diskettes using the Deluxe Option Board, from Central Point software. We also offer an in-depth users manual, complete with figures and technical references, printed and professionally bound. In the real world, however, we realize that many people will not pay the registration fee regardless of any incentives we provide. While we don't want to remove the incentive to register, we also don't want to make it impossible to use SimSystem IIe with anything but the few demo programs we provide with it. In fact, some people may choose NOT to register until they can verify whether SimSystem IIe is compatible with specific Apple II software. For this reason we are providing a description of the volume files used by SimSystem IIe. Any moderately skilled programmer will be able to create a program that can generate the volume files. Who knows - maybe we'll offer to include such a program with future shareware versions of SimSystem IIe, and share the registration fee with the programs author... (It would have to be REALLY good, though...) Floppy (*.IIE) Volumes Floppy volume files come in two basic flavors; binary and GCR. Both types have the DOS extension *.IIE, and both types begin with a header, as follows: 13 bytes - ASCII text "SIMSYSTEM_IIE" 1 byte - volume type, as follows: 00 - binary ProDOS volume 01 - binary Apple DOS volume 02 - binary unknown operating system 03 - GCR unknown operating system All of the binary formats, 0 through 2, are treated the same by SimSystem IIe. The reference to which operating system format they use is for informational purposes only. Utility programs should NOT count on this value to determine the directory format for the volume data. All of the binary format volume files continue, as follows: 16 bytes - sector interleave table This table indicates the physical order of the sectors in each track image. SimSystem IIe uses this information to create sector address fields when generating GCR data from the volume file data. 4096 bytes - track 0 data 4096 bytes - track 1 data Page 22 ... 4096 bytes - track 34 data All of the GCR format volume files continue, as follows: 37 words - track size table GCR volumes contain data for 37 tracks (as opposed to the normal 35 tracks on an Apple disk). This is in support of the those Apple copy protection schemes that use extra tracks at the inside diameter of the disk. Each word in this table (in Intel low byte/high byte order) indicates the size of each GCR track image in bytes. ???? bytes - track 0 GCR data ???? bytes - track 1 GCR data ... ???? bytes - track 36 GCR data Hard Disk (*.HDV) Volumes SimSystem IIe hard disk volumes always contain binary data. In addition, they are only compatible with Apple ProDOS operating systems. For this reason, the data are stored in ProDOS blocks (512 bytes each). The format of a SimSystem IIe hard disk volume file is as follows: 13 bytes - ASCII text "SIMSYSTEM_HDV" 1 word - size of the volume (low byte/high byte) in ProDOS blocks 512 bytes - block 0 data 512 bytes - block 1 data ... 512 bytes - last block data Given the appropriate boot sector data, these volume files can be used to boot SimSystem IIe. Curiously enough, the Apple boot sector for a ProDOS volume is identical for a hard drive and a floppy disk. SimSystem IIe hard drive ROM code (slot 7) conforms to the Apple standard for a hard disk, and will boot ProDOS from a standard Apple volume. Good Luck!!! Page 23 Appendix - Registration _______________________ Hopefully, all of this has given you sufficient enticement to break out your check book and send in your registration. The registration fee is $50 U.S., plus $6 to cover shipping costs. Make out your check to: American Research Inc. 2120 Deercreek Rd. Simi Valley, CA 93065 California residents should add the appropriate sales tax. Your registered copy of SimSystem IIe will be sent out as soon as your check has cleared. You can save some time by sending a money order or cashiers check, which will get you same day service.